IronWrap CodeRivets

SoftwareShield System Feature Guide > IronWrapping > Code Rivets

## IronWrap CodeRivets

### What are CodeRivets?

CodeRivets are a proprietary technology used in IronWrapping your products. You may use manually inserted CodeRivets to add a special layer of additional protection in select areas of your program. While CodeRivets do require changes to your source code, the changes are very small. Adding CodeRivets manually to your program adds a significant layer of protection to the overall strength of the system. Of course adding CodeRivets to your program is completely optional and you may simply choose to IronWrap a program without them and feel confident that you are using the strongest DRM system available today.

A (manually inserted) CodeRivet is actually a pair of two delimiters, a "begin" CodeRivet and a matching "end" CodeRivet. Here is an example of a CodeRivet pair definition (for CodeRivet #1 for the Borland C++ compiler).

#define RIVETBEGIN_1 __emit__ (0xEB,0x07,0xD4,0x4D,0x09,0xFF,0x5A,0x0A,0xB7)
#define RIVETEND_1 __emit__ (0xEB,0x07,0xB7,0x0A,0x5A,0xFF,0x09,0x4D,0xD4)

There are 10 defined CodeRivets. These definitions are found in the header and include files "CodeRivets.h", and "CodeRivets.inc". These CodeRivets can be included from your programs in most compilers. Definitions are provided in these files for Microsoft Visual C++ and Borland C++ and Delphi. CodeRivets can not be inserted into .NET applications (even in unmanaged sections). Each CodeRivet has its own separate encryption key. This key is used to encrypt the code within the rivet (see below).

### What Do CodeRivets Do?

When you use CodeRivets in your programs, during development they do absolutely nothing. That is, while they are compiled into your program as executable code, during execution they essentially have a zero (noticeable) behaviour. Therefore, if you are single stepping your program during development in your IDE, and execution reaches a CodeRivet, execution will simply pass right over the "begin" rivet delimiter and carry on (inside the rivet), and similarly, will pass right over the "end" delimiter.

When you eventually link the host program (containing CodeRivets) in the SoftwareShield License Manager using the IronWrapper, the IronWrap Linker parses the compiled executable for CodeRivets, and when found will individually encrypt those code sections, modify the rivet delimiters themselves and perform various other proprietary operations to facilitate run-time handling of the Rivets. Once the CodeRivet encryption is complete, the entire host is (optionally) encrypted. This achieves a layered encryption effect - so that even after the host is decrypted in memory, the CodeRivets contained within the decrypted executable image remain encrypted.

When execution of the IronWrapped product reaches a CodeRivet, the system detects this and if the system does not yet have the key to decrypt the CodeRivet, execution simply passes right over the entire CodeRivet block. However, if the system does have the key to decrypt the CodeRivet, it is immediately decrypted into a special temporary secure memory buffer, where it is executed, and as soon as execution leaves the CodeRivet the memory is burned. Thus, at a maximum, only one Rivet at a time is ever decrypted.

### How do I Use CodeRivets?

You use CodeRivets simply by wrapping blocks of any executable code in your programs in a "begin" and matching "end" CodeRivet. You must also check "Host Uses CodeRivets" checkbox your License Project (in the License Manager).

Delimiters must match correctly, or the IronWrap linker will generate an error at link time. You may use any number of the 10 CodeRivets in your programs. EG: You may use 5 blocks of CodeRivet #1 and 0 blocks of CodeRivet #2 and 100 blocks of CodeRivet #3, etc. Blocks may be nested for added security of very sensitive sections.

CodeRivets do slow down execution slightly, so you must be sure not to use CodeRivets in areas of your program that are executed very frequently or performance critical algorithms (like Windows message handlers or graphics processing routines).

Here is an example of a CodeRivet is use. Below you will see a small function that has a CodeRivet:

void TForm1::Button1Click(TObject *Sender)
{

RIVETBEGIN_1;

MessageBox(NULL, "Rivet 1","Hello from inside Rivet 1", MB_OK);
return;

RIVETEND_1;
MessageBox(NULL, "No Rivet Key","No Rivet Key", MB_OK);

}

Also note that CodeRivets can not be nested. A CodeRivet placed within another CodeRivet will produce undesirable effects.

Here is an example of CodeRivets that would function properly:

void TForm1::Button1Click(TObject *Sender)
{

RIVETBEGIN_1;

MessageBox(NULL, "Rivet 1","Hello from inside Rivet 1", MB_OK);
return;

RIVETEND_1;
RIVETBEGIN_2;

MessageBox(NULL, "Rivet 2","Hello from inside Rivet 2", MB_OK);
return;

RIVETEND_2;

}

The following is an example of CodeRivets that would NOT function properly:

void TForm1::Button1Click(TObject *Sender)
{

RIVETBEGIN_1;

MessageBox(NULL, "Rivet 1","Hello from inside Rivet 1", MB_OK);
return;

RIVETBEGIN_2;

MessageBox(NULL, "Rivet 2","Hello from inside Rivet 2", MB_OK);
return;

RIVETEND_2;

RIVETEND_1;

}

You can see from the function that if the system did not have a key for CodeRivet #1, that the user would click on "Button1" and see the message "No Rivet Key". However, if you did unlock CodeRivet #1, the user would see "Hello from inside Rivet 1". The second message would never be shown because of the return statement inside the CodeRivet - which would always execute after the CodeRivet was unlocked.

### How do I Unlock CodeRivets?

You unlock CodeRivets by performing a Code Exchange with your user. When you send an Activation Code (or Serial Number) that ultimately unlocks a CodeRivet, the key (called the CodeRivet exponent) for decrypting that CodeRivet type in your license is sent to the users main license file on their machine. From that point forward all instances of that CodeRivet type is unlocked on that users machine.

Note that when a CodeRivet is unlocked, it remains encrypted just like before, the only difference is that the system can decrypt it when necessary.

### More Information

For more information on actually setting the License Project to use CodeRivets, see: CodeRivets Tab